Prep Work for #74 — Find People Using a Reference Image

The Bug

Actor indexing detects a face, aligns it, and computes a normalized SFace encoding for each detection — but that encoding was never actually persisted.

_actor_records() was writing a placeholder embedding=[0.0] into every StorageRecord sent to Chroma. As a result, the actor collection's vector index has never contained real, searchable face embeddings.

During indexing, matching only used ActorIndexState.known_encodings, which is an in-memory list scoped to a single indexing run and discarded once the run finishes.

This silently blocks #74: finding a person using a reference image requires comparing a new face embedding against all previously detected faces across the repository, but there was no durable embedding data to compare against.

The Fix

• Carry the computed encoding through into each detection dictionary in process_actor_samples.
• Update _actor_records() to persist the real, normalized encoding as StorageRecord.embedding instead of [0.0].
• Leave _actor_cluster_records() unchanged. A cluster summary spans multiple detections and does not represent a single face image, so it has no single embedding to persist.

Schema Version Bump

Because this changes what is actually persisted for each actor detection, existing generations with the actor modality enabled contain placeholder vectors and are no longer trustworthy for face search.

The repository already has a mechanism for handling this:

• CompletedGenerationManifest.index_schema_version is typed as Literal[INDEX_SCHEMA_VERSION].
• local_snapshots.py::validate_generation() validates the manifest on disk using model_validate_json().
• ValidationError is explicitly caught and re-raised as IndexSchemaError.

This PR bumps INDEX_SCHEMA_VERSION from 7 → 8.

As a result, old generations will fail validation cleanly with IndexSchemaError instead of silently being treated as complete, searchable indexes containing meaningless vectors.

User-facing impact

Any existing generation with the actor modality enabled will need to be re-indexed after this change.

This is intentional. The alternative would be allowing #74 to search against invalid placeholder embeddings with no indication that the underlying data is unusable.

Testing

New test

Added:

test_actor_indexing_persists_real_face_embeddings_not_placeholders

This drives process_actor_samples through mocked YuNet/SFace calls end-to-end and verifies that the StorageRecord sent to storage.upsert contains the real normalized encoding rather than the placeholder [0.0].

Updated test

Updated:

test_actor_records_preserve_stable_detection_metadata

The test previously created fake detection dictionaries without an encoding field. It now provides an explicit encoding and verifies that the resulting StorageRecord.embedding matches the real value.

Test results

Full test suite:

590 passed, 2 skipped, 0 failed

Also re-ran the tests covering INDEX_SCHEMA_VERSION and actor indexing:

• test_generation_manifest.py
• test_local_snapshots.py
• test_indexing.py
• test_actor_results.py
• test_cli.py
• test_frontend_app.py

All tests pass, including the existing test that constructs a manifest with INDEX_SCHEMA_VERSION + 1 to verify that the rejection path still works.

Not Included

This PR does not implement reference-image search itself.

Reference-image search remains the actual feature tracked by #74 and will be implemented as a separate follow-up PR once this change lands, since it depends on real actor embeddings being persisted first.